home *** CD-ROM | disk | FTP | other *** search
/ Inter.Net 55-1 / Inter.Net 55-1.iso / CBuilder / Setup / BCB / data.z / grep.txt < prev    next >
Encoding:
Text File  |  1998-02-09  |  11.5 KB  |  268 lines
  1. Grep Help
  2.  
  3. GREP (Global Regular Expression Print) is a powerful text-search program derived from the
  4. UNIX utility of the same name. GREP searches for a text pattern in one or more files or in its
  5. standard input stream.
  6. Here is a quick example of a situation where you might want to use GREP. Suppose you wanted
  7. to find out which text files in your current directory contained the string "Bob". You would type:
  8.  
  9. grep Bob *.txt
  10.  
  11. GREP responds with a list of the lines in each file (if any) that contained the string "Bob".
  12. Because GREP does not ignore case by default, the strings "bob" and "boB" do not match.
  13. GREP can do a lot more than match a single, fixed string. In the following section, you will see
  14. how to make GREP search for any string that matches a particular pattern.
  15.  
  16. The general command-line syntax for GREP is
  17.  
  18. grep [-options] searchstring [file(s) ... ]
  19.  
  20. Option    Description
  21.  
  22. options   consist of one or more letters, preceded by a hyphen (-), that changes the behavior
  23. of GREP.
  24. searchstring   gives the pattern to search for.
  25. file(s)   tells GREP which files to search. (If you do not specify a file, GREP searches standard
  26. input; this lets you use pipes and redirection.)
  27.  
  28. The command GREP ? prints a help screen showing the options, special characters, and defaults
  29. for GREP.
  30.  
  31. Redirecting Output from GREP
  32.  
  33. If you find that the results of your GREP are longer than one screen, you can redirect the output
  34. to a file. For example, you could use this command:
  35.  
  36. GREP "Bob" *.txt > temp.txt
  37.  
  38. which searches all files with the TXT extension in the current directory, then puts the results in a
  39. file called TEMP.TXT. (You can name this file anything you like.) Use any word processor to
  40. read TEMP.TXT (the results of the search).
  41.  
  42. You can pass options to the GREP utility on the command line by specifying one or more single
  43. characters preceded by a hyphen (-). Each individual character is a switch that you can turn on or
  44. off: A plus symbol (+) after a character turns the option on; a hyphen (-) after the character turns
  45. the option off. The + sign is optional; for example, -r means the same thing as -r+. You can list
  46. multiple options individually (like this: -i -d -l), or you can combine them (like this: -ild or -il, -d,
  47. and so on).
  48.  
  49. Here are the GREP option characters and their meanings:
  50.  
  51. Option    Description
  52.  
  53. -c   Count only: Prints only a count of matching lines. For each file that contains at least one
  54. matching line, GREP prints the file name and a count of the number of matching lines. Matching
  55. lines are not printed. This option is off by default.
  56. -d   Search subdirectories: For each file specified on the command line, GREP searches for all
  57. files that match the file specification, both in the directory specified and in all subdirectories
  58. below the specified directory. If you give a file without a path, GREP assumes the files are in the
  59. current directory. This option is off by default.
  60.  
  61. -i   Ignore case: GREP ignores upper/lowercase differences. When this option is on, GREP
  62. treats all letters a to z as identical to the corresponding letters A to Z in all situations. This option
  63. is off by default.
  64. -l   List file names only: Prints only the name of each file containing a match. After GREP
  65. finds a match, it prints the file name and processing immediately moves on to the next file. This
  66. option is off by default.
  67. -n   Line numbers: Each matching line that GREP prints is preceded by its line number. This
  68. option is off by default.
  69.  
  70. -o   UNIX output format: Changes the output format of matching lines to support more easily
  71. the UNIX style of command-line piping. All lines of output are preceded by the name of the file
  72. that contained the  matching line. This option is off by default.
  73. -r   Regular expression search: The text defined by searchstring is treated as a regular
  74. expression instead of as a literal string. This option is on by default. A regular expression is one
  75. or more occurrences of one or more characters optionally enclosed in quotes. The following
  76. symbols are treated specially:
  77.  
  78. ^  start of line    $  end of line
  79.      .  any character    \  quote next character
  80.      *  match zero or more    +  match one or more
  81.  
  82. [aeiou0-9]     match a, e, i, o, u, and 0-9
  83.      [^aeiou0-9]    match all but a, e, i, o, u, and 0-9
  84.  
  85. -u   Update options: GREP adds any options from the command line to its default options in
  86. GREP.COM. This option lets you to customize the default option settings. To see the defaults are
  87. set in GREP.COM, type GREP ?, then each option on the help screen is followed by a + or a -
  88. depending on its default setting.
  89. -v   Nonmatch: Prints only nonmatching lines. Only lines that do not contain the search string
  90. are considered nonmatching lines. This option is off by default.
  91.  
  92. -w   Word search: Text found that matches the regular expression is considered a match only
  93. if the character immediately preceding and following cannot be part of a word. The default word
  94. character set includes A to Z, 0 to 9, and the underscore ( _ ). This option is off by default. An
  95. alternate form of this option lets you specify the set of legal word characters. Its form is -w[set],
  96. where set is any valid regular expression.
  97.      If you define the set with alphabetic characters, it is automatically defined to contain both
  98. the uppercase and lowercase values for each letter in the set (regardless of how it is typed), even
  99. if the search is case-sensitive. If you use the -w option in combination with the -u option, the new
  100. set of legal characters is saved as the default set.
  101.  
  102. -z   Verbose: GREP prints the file name of every file searched. Each matching line is
  103. preceded by its line number. A count of matching lines in each file is given, even if the count is
  104. zero. This option is off by default.
  105. ?    Displays a help screen showing the options, special characters, and defaults for GREP.
  106.  
  107. The value of searchstring defines the pattern GREP searches for. A search string can be either a
  108. regular expression or a literal string.
  109.  
  110. In a regular expression, certain characters have special meanings: They are operators that govern
  111. the search.
  112.      In a literal string, there are no operators: Each character is treated literally.
  113.  
  114. You can enclose the search string in quotation marks to prevent spaces and tabs from being
  115. treated as delimiters. The text matched by the search string cannot cross line boundaries; that is,
  116. all the text necessary to match the pattern must be on a single line.
  117. A regular expression is either a single character or a set of characters enclosed in brackets. A
  118. concatenation of regular expressions is a regular expression.
  119. When you use the -r option (on by default), the search string is treated as a regular expression
  120. (not a literal expression). The following characters have special meanings:
  121.  
  122. Symbol    Description
  123.  
  124.  ^   A circumflex at the start of the expression matches the start of a line.
  125.  $   A dollar sign at the end of the expression matches the end of a line.
  126.  .   A period matches any character.
  127.  *   An asterisk after a string matches any number of occurrences of that string followed by
  128. any characters, including zero characters. For example, bo* matches bot, boo, and as well as bo.
  129.  
  130.  +   A plus sign after a string matches any number of occurrences of that string followed by
  131. any characters, except zero characters. For example, bo+ matches bot and boo, but not b or bo.
  132. { }  Characters or expressions in braces are grouped so that the evaluation of a search pattern
  133. can be controlled and so grouped text can be referred to by number.
  134. [ ]  Characters in brackets match any one character that appears in the brackets, but no others.
  135. For example [bot] matches b, o, or t.
  136.  
  137. [^]  A circumflex at the start of the string in brackets means NOT. Hence, [^bot] matches any
  138. characters except b, o, or t.
  139. [-]  A hyphen within the brackets signifies a range of characters. For example, [b-o] matches
  140. any character from b through o. 
  141.   \       A backslash before a wildcard character tells the C++ IDE to treat that character literally,
  142. not as a wildcard. For example, \^ matches ^ and does not look for the start of a line.
  143.  
  144. Four of the "special" characters ($, ., *, and +) do not have any special meaning when used
  145. within a bracketed set. In addition, the character ^ is only treated specially if it immediately
  146. follows the beginning of the set definition (immediately after the [ delimiter).
  147.  
  148. The files option tells GREP which files to search. Files can be an explicit file name or a generic
  149. file name  incorporating the DOS ? and * wildcards. In addition, you can type a path (drive and
  150. directory information). If you list files without a path, GREP searches the current directory. If
  151. you do not specify any files, input to GREP must come from redirection (<) or a vertical bar (|).
  152.  
  153. These examples show how to combine the features of GREP to do different kinds of searches.
  154. They assume default settings for GREP are unchanged.
  155.  
  156. grep -r [^a-z]main\ *( *.c
  157. grep -ri [a-c]:\\data\.fil *.c *.inc
  158. grep "search string with spaces" *.doc *.c
  159. grep -rd "[ ,.:?'\"]"$ \*.doc
  160. grep -w[=] = *.c
  161.  
  162. Command
  163.  
  164. grep -r [^a-z]main\ *( *.c
  165.  
  166. Matches
  167.  
  168. main(i,j:integer)
  169. if (main  ()) halt;
  170. if (MAIN  ()) halt;
  171.  
  172. Does Not Match
  173.  
  174. mymain()
  175.  
  176. Explanation
  177.  
  178. The search string tells GREP to search for the word main with no preceding lowercase letters
  179. ([^a-z]), followed by zero or more occurrences of blank spaces (\ *), then a  left parenthesis.
  180. Since spaces and tabs are normally  considered command-line delimiters, you must quote them if
  181. you want to include them as part of a regular expression. In this case, the space after main is
  182. quoted with the backslash escape character. You could also accomplish this by placing the space
  183. in double quotes.
  184.  
  185. Command
  186.  
  187. grep -ri [a-c]:\\data\.fil *.c *.inc
  188.  
  189. Matches
  190.  
  191. A:\data.fil
  192. B:\DATA.FIL
  193. c:\Data.Fil
  194.  
  195. Does Not Match
  196.  
  197. d:\data.fil
  198. a:data.fil
  199.  
  200. Explanation
  201.  
  202. Because the backslash (\) and period (.) characters usually have special meaning in path and file
  203. names, you must place the backslash escape character  immediately in front of them if you want
  204. to search for them. The -i option is used here, so the search is not case sensitive.
  205.  
  206. Command
  207.  
  208. grep "search string with spaces" *.doc *.c
  209.  
  210. Matches
  211.  
  212. This is a search string with spaces in it.
  213.  
  214. Does Not Match
  215.  
  216. This search string has spaces in it.
  217.  
  218. Explanation
  219.  
  220. This is an example of how to search for a string with embedded spaces.
  221.  
  222. Command
  223.  
  224. grep -rd "[ ,.:?'\"]"$ \*.doc
  225.  
  226. Matches
  227.  
  228. He said hi to me.
  229. Where are you going?
  230. In anticipation of a unique situation,
  231. Examples include the following:
  232. "Many men smoke, but fu man chu."
  233.  
  234. Does Not Match
  235.  
  236. He said "Hi" to me
  237. Where are you going? I'm headed to the
  238.  
  239. Explanation
  240.  
  241. This example searches for any one of the characters " . : ? ' and , at the end of a line. The double
  242. quote within the range is preceded by an escape character so it is treated as a normal character
  243. instead of as the ending quote for the string. Also, the $ character appears outside of the quoted
  244. string. This demonstrates how regular expressions can be concatenated to form a longer
  245. expression.
  246.  
  247. Command
  248.  
  249. grep -w[=] = *.c
  250.  
  251. Matches
  252.  
  253. i = 5;
  254. j=5;
  255. i += j;
  256.  
  257. Does Not Match
  258.  
  259. if (i == t) j++;
  260. /* =================== */
  261.  
  262. Explanation
  263.  
  264. This example redefines the current set of legal characters for a word as the assignment operator
  265. (=) only, then does a word search. It matches C assignment statements, which use a single equal
  266. sign (=), but not equality tests, which use a double equal sign (==).
  267.  
  268. Copyright   1998 Borland International.